home *** CD-ROM | disk | FTP | other *** search
/ BBS in a Box 15 / BBS in a box XV-1.iso / Files / System 7 / M / Menu Events 1.2.sit / Menu Events 1.2 / Menu Events Help.rsrc / STR#_1027.txt < prev    next >
Encoding:
Text File  |  1994-10-17  |  6.5 KB  |  267 lines
  1. 
  2.  
  3. 
  4.  
  5. ‹
  6.  
  7. ‹
  8.  
  9. √•How Does Menu Events Work?
  10.  
  11. 
  12.  
  13. 
  14.  
  15. When you send a Query Menu List or Query Menu event, the ideal
  16.  
  17. application will dispatch the resulting high-level event as an Apple event
  18.  
  19. without looking at it.  The event handler provided by Menu Events forms a
  20.  
  21. reply to the query on the basis of the application‚Äôs menu list structure.  In
  22.  
  23. the case of a Query Menu event, if the given menu ID is not valid, it
  24.  
  25. returns noSuchMenuErr.  Through all of this, the application stays in the
  26.  
  27. background or in the foreground, wherever it was before.
  28.  
  29. 
  30.  
  31. 
  32.  
  33. When you send a Select Menu Item event, the same things happen, but the
  34.  
  35. event handling is more complex.
  36.  
  37. 
  38.  
  39. First, it verifies that the given menu item is valid and enabled.  If not, it
  40.  
  41. returns noSuchMenuErr, noSuchMenuItemErr, or menuItemDisabledErr.  If
  42.  
  43. the menu has a non-standard menu definition procedure, its way of
  44.  
  45. counting or disabling items may differ from the norm.  Menu Events
  46.  
  47. assumes that the count and enable/disable flags are set in the normal
  48.  
  49. fashion.
  50.  
  51. 
  52.  
  53. Second, it asks for the application to be brought to the front for user
  54.  
  55. interaction, because it could be dangerous to feed the target application a
  56.  
  57. menu selection while it is in the background, something which never
  58.  
  59. happens in normal operation.  If it is refused, it returns
  60.  
  61. errAENoUserInteraction.
  62.  
  63. 
  64.  
  65. Third, it patches some traps so that it can gain control of menu selection.
  66.  
  67. If it finds that the patches are already in place, meaning that an earlier
  68.  
  69. Menu event is still pending, it returns menuEventPendingErr.
  70.  
  71. 
  72.  
  73. Fourth, if everything is OK, it posts an event to simulate a mouse click in
  74.  
  75. the menu bar, with modifier keys if specified.  The application habitually
  76.  
  77. asks which menu item was selected, and the patched traps provide the
  78.  
  79. given item in response.  The patches then remove themselves.  From
  80.  
  81. there, it is exactly as though the user had actually made the selection.
  82.  
  83. 
  84.  
  85. NOTE:  When replying to any of the three event types, Menu Events
  86.  
  87. includes a null ‚Äútattoo‚Äù parameter to prove that it handled the event,
  88.  
  89. rather than some handler supplied by the application.  Many Microsoft
  90.  
  91. applications, for example, bind their own handler over all Apple event
  92.  
  93. classes, preventing Menu Events from working.  (The handler wouldn‚Äôt be
  94.  
  95. a problem if it returned errAEEventNotHandled when faced with an
  96.  
  97. unknown Apple event, as it should.)
  98.  
  99. 
  100.  
  101. 
  102.  
  103. 
  104.  
  105. xUser Interaction Policy
  106.  
  107. 
  108.  
  109. The Apple Event Manager implements a complicated but sensible model for
  110.  
  111. joint sender/receiver control over user interaction.  Menu Events doesn‚Äôt
  112.  
  113. know which menu selections will really require user interaction, but even
  114.  
  115. if it did, it would still have to request user interaction just to bring the
  116.  
  117. target application to the front, where an application always expects to be
  118.  
  119. when it sees a mouse-down event.
  120.  
  121. 
  122.  
  123. 
  124.  
  125. The sending program must set the kAECanInteract or kAEAlwaysInteract
  126.  
  127. flag in the sendMode parameter to AESend, in order to achieve user
  128.  
  129. interaction.  It should also set the kAECanSwitchLayer flag, allowing the
  130.  
  131. target application to come to the front without having to post a
  132.  
  133. notification request.  If the target application is in the background, and
  134.  
  135. receives a Menu event with this flag not set, it may go into a notification
  136.  
  137. wait state, disrupting its usual background event processing behavior.
  138.  
  139. 
  140.  
  141. If both the sending program and target application are in the background,
  142.  
  143. the kAECanSwitchLayer flag has no effect, and the notification request is
  144.  
  145. posted anyway.  Since your sending program is indirectly instigating a
  146.  
  147. user interaction, it should call AEInteractWithUser before sending the
  148.  
  149. Menu event, if there is any chance that it will be in the background at the
  150.  
  151. time.  Another approach would be to call SetFrontProcess to activate the
  152.  
  153. target application before sending it a Menu event.
  154.  
  155. 
  156.  
  157. If the target application is in that rare user interaction state,
  158.  
  159. kAEInteractWithSelf, where it disallows interaction requested by any
  160.  
  161. other process, the Menu event handler will respect that state, and refuse
  162.  
  163. the event.
  164.  
  165. 
  166.  
  167. If the sending and receiving applications are on different machines, the
  168.  
  169. usual program linking checks apply, namely, Sharing Setup (on/off),
  170.  
  171. Users & Groups (permission to user), and Finder‚Äôs Sharing (permission to
  172.  
  173. application).
  174.  
  175. 
  176.  
  177. If the Menu Events extension is locked, using Finder‚Äôs Get Info dialog, then
  178.  
  179. only target applications which explicitly allow interaction with all
  180.  
  181. processes can be controlled by remote senders.  If it is not locked, and if
  182.  
  183. it sees that the user interaction state is kAEInteractWithLocal, which is
  184.  
  185. the default value, it will momentarily change it to kAEInteractWithAll, so
  186.  
  187. that events sent from a remote machine are not rejected.  This trick is
  188.  
  189. necessary for Menu Events to be useful with most target applications,
  190.  
  191. because most will assume the default interaction state, not expecting any
  192.  
  193. remote sender to require user interaction.  The icon displayed by Menu
  194.  
  195. Events at startup shows whether or not the lock is in effect.
  196.  
  197. 
  198.  
  199. IMPORTANT NOTE:  Users of machines where Menu Events is installed
  200.  
  201. should be careful about which users and applications are enabled for
  202.  
  203. remote program linking.  In particular, guest users should not be allowed
  204.  
  205. to do program linking unless Menu Events is locked.
  206.  
  207. 
  208.  
  209. 
  210.  
  211. 
  212.  
  213. xSelf-Sending Behavior
  214.  
  215. 
  216.  
  217. When you are using a high-level-event-aware application on a machine
  218.  
  219. where Menu Events is installed, menu item selection behavior is modified
  220.  
  221. if the Caps Lock key is down at the time you release the mouse button.
  222.  
  223. Menu Events will try to nullify the menu selection and replace it with a
  224.  
  225. self-addressed Select Menu Item event (including parameters for any
  226.  
  227. modifier keys which were pressed), so that a script editor can record the
  228.  
  229. event as a script command.  A gentle ‚Äútwang‚Äù sound confirms that this
  230.  
  231. has happened.  If it fails to send this event, the menu selection will be
  232.  
  233. processed in the usual way.
  234.  
  235. 
  236.  
  237. 
  238.  
  239. If the application is scriptable in its own right, a script editor may record
  240.  
  241. two commands when you select an item from its menus.  To prevent this
  242.  
  243. duplication, you can use the item‚Äôs Command-key equivalent (if any), or
  244.  
  245. release the Caps Lock key, to suppress the self-sending behavior.
  246.  
  247. 
  248.  
  249. If an application seems to be misinterpreting or not receiving menu
  250.  
  251. selections, try again with the Caps Lock key up.  The command will not be
  252.  
  253. recorded, but should work as usual.
  254.  
  255. 
  256.  
  257. NOTE:  While receiving a Select Menu Item event does simulate a menu
  258.  
  259. selection, it does not cause a Select Menu Item script command to be
  260.  
  261. recorded.
  262.  
  263. 
  264.  
  265. 
  266.  
  267.